package com.maikobi.maikobi.annotation;

import java.lang.annotation.*;
import java.util.concurrent.TimeUnit;

/**
 * 自定义限流注解，基于 Redisson 实现的分布式限流器。
 * <p>
 * 可用于注解在 Controller 或 Service 方法上，实现对指定方法的访问速率控制。
 * 支持通过 key 区分不同的限流维度（如不同用户、IP、接口等），
 * 并支持自定义单位时间内的最大访问次数。
 * <p>
 * 使用示例：
 * <pre>{@code
 * @RateLimiter(key = "genChart", permits = 5, time = 1, unit = TimeUnit.SECONDS)
 * public Result generateChart() {
 *     ...
 * }
 * }</pre>
 *
 * @author Maiko7
 * @create 2025-07-14 8:17
 */
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface RateLimiter {

    /**
     * 限流键，通常用于区分不同的限流粒度。
     *
     * @return 限流唯一键
     */
    String key() default "";

    /**
     * 指定单位时间内允许的最大访问次数。
     *
     * @return 最大请求数
     */
    long permits() default 1;

    /**
     * 时间间隔数，与 {@link #unit()} 一起使用。
     * <p>
     * 例如：time = 1，unit = SECONDS 表示 “每秒允许 1 次访问”
     *
     * @return 时间间隔值
     */
    long time() default 1;

    /**
     * 时间单位，默认为秒。
     *
     * @return 时间单位 {@link TimeUnit}
     */
    TimeUnit unit() default TimeUnit.SECONDS;
}